home *** CD-ROM | disk | FTP | other *** search
/ Loadstar 128 27 / q27.d81 / t.dt128 docs 9 < prev    next >
Text File  |  2022-08-28  |  15KB  |  432 lines
  1.  
  2.  
  3.  Script Compiler
  4.  ---------------
  5.  
  6. A script is a program which you create and run within the DT128
  7. environment.  The program is created using DT128's very own script
  8. language. The language adds a powerful set of instructions which can be
  9. used to perform various useful tasks which enables you customize the
  10. operations of your terminal.
  11.  
  12. Each script consists of 2 parts: source code and executable code.  The
  13. source code is the actual program you create within the main buffer editor.
  14. It is the series of script language instructions you need to perform a
  15. task.  This program must then be compiled using the "Script Compiler"
  16. module.  The compiler translates the source code in the buffer to
  17. executable code.  It is the executable code that actually runs within DT128
  18. using the "Execute Script" module.
  19.  
  20. If there is a syntax error within your source code the compiler will report
  21. the error type as well as a memory location value.  This value is the
  22. offset into the buffer where the error occurred (in the editor you can
  23. press Keypad-6 and enter the value to move to that location quickly).  Fix
  24. the error and re-compile.  When the source code is free of syntax errors
  25. the executable code is created.  You then have the option to save the code
  26. to disk.  You may enter a file name of up to 12 characters.  The file
  27. extension ".exe" is automatically appended to the name you provide.  While
  28. it is the EXEcutable file that you run you should also save your source
  29. code to a disk file.  That way if you need to make changes to your script
  30. program you can re-load your source code, modify it, re-save it, then
  31. compile the new code to create a new executable file.
  32.  
  33.  
  34. How to Create a Script:
  35.  
  36. The first step is to load the "Script Compiler" module.  You edit your
  37. script programs using the main buffer editor.  There are many instructions
  38. you may use, each of which is listed below as well as an explanation of
  39. what each does.
  40.  
  41. General Source Code Syntax:
  42.  
  43.     1. All script language instructions must be fully capitalized.
  44.  
  45.     2. A "label" is similar to BASIC's "variable" in that the usage is
  46. similar.  There are 3 types of labels:
  47.  
  48.        A. Numeric (created with the NUMBER instruction, similar to an
  49. integer variable in BASIC)
  50.        B. string (created with the STRING instruction, similar to a string
  51. variable in BASIC)
  52.        C. address (these labels are defined by you and they give names to
  53. portions of your program, similar to BASIC line numbers)
  54.  
  55.     3. Labels must be entirely lower case (the underscore "{CBM-@}" and digits 0-
  56. 9 are valid as long as they are not the 1st character in the label.
  57.  
  58.        Valid: file{CBM-@}name  counter1   Invalid: {CBM-@}counter 1counter
  59.  
  60.     4. Labels can be up to 32 characters in length.
  61.  
  62.     5. A semi colon can be used to insert comments in your source code.
  63.  
  64.        ; comments follow up to next return
  65.  
  66.     6. Strings can be delimited with either a quote or apostrophe.  If you
  67. use a quote at the front of a string you must end the string with a quote,
  68. if you use an apostrophe to start a string you must end the string with an
  69. apostrophe.
  70.  
  71.        Valid: "string" or 'string'   Invalid "string'
  72.  
  73.     7. Spacing is not important (you can indent or space commands and
  74. labels in any format that you like to create more legible code)
  75.  
  76.     8. All strings are interpreted literally.  This can cause certain
  77. problems.  For example, the editor uses standard ASCII codes.  File names,
  78. however, should be PetAscii.  Upper case ASCII characters correspond to
  79. lower case PetAscii characters.  Because no string conversions are
  80. performed you will usually want to use upper case letters in file names, as
  81. well as any string that you DISPLAY or TRANSMIT to a C/G screen.  An easy
  82. way to get it correct is any time you enter a file name or any string that
  83. is to be used in a PetAscii environment you turn on PetAscii input mode
  84. while entering the string.
  85.  
  86. Refer to Command Set further in the document for a listing of
  87. instructions.
  88.  
  89.  Execute Script
  90.  --------------
  91.  
  92. After you have successfully compiled a script you can run it using this
  93. module. Select the "Load Script" option and enter a 12 character file name
  94. (the file extension ".exe" is automatically appended to the name).  If the
  95. file is a valid script file you can then run it in 2 different ways:
  96.  
  97.          1. Select the "Execute Script" option within the module.
  98.  
  99.          2. Press Alt-V in terminal mode.
  100.  
  101. Scripts can be aborted by pressing the RUN/STOP key.  When a script ends or
  102. is aborted you are returned to this module.  When you press ESCape to exit
  103. the module you return to terminal mode if you ran the script using Alt-V
  104. from terminal mode or to the previous menu if you ran it from within the
  105. module.
  106.  
  107. There are several possible messages you will see when a script ends:
  108.  
  109.    Stopped - the script ended or you pressed RUN/STOP.
  110.  
  111.    Buffer Overflow - you attempted to load a file but the buffer was filled
  112. before the entire file could be loaded.
  113.  
  114.    Stack Overflow - You nested too many subroutines (a subroutine called a
  115. subroutine which called a subroutine...) or a RETURN was attempted without
  116. a PERFORM previous.
  117.  
  118. You can execute a script upon BOOTUP by naming the script executable file
  119. "AUTOEXEC".
  120.  
  121. Executable scripts are version dependent.  You will need to re-compile all
  122. source code files with each update.
  123.  
  124. The Command Set:
  125.  
  126. NUMBER
  127.  
  128.      Allows you to define a numeric variable.  In the script language all
  129. defined numeric variables are 16 bit integers which means that a variable
  130. can have a whole number value from 0 - 65,535.
  131.  
  132.      Syntax: NUMBER label x
  133.  
  134. where "label" is the variable name and "x" is its initial value (0-65535).
  135. The initial value is valid only the first time you run the script after it
  136. is loaded.  If you re-execute a script the numeric value starts at whatever
  137. value it had when the script was stopped.  Any instruction that requires 1
  138. or more numeric parameters can use a numeric label except where noted.
  139.  
  140. STRING
  141.  
  142.      Allows you to define a string variable.  In the script language all
  143. strings must be 1-255 characters is length and may contain any characters.
  144.  
  145.      Syntax: STRING label "string"
  146.              STRING label 'string'
  147.  
  148. where "label" is the name of the string variable.  The string can be
  149. comprised of any character as long as it has the same delimiter, the quote
  150. or apostrophe, starting and ending it.  If you place a return (Ascii 13)
  151. inside the string the listing will look a bit odd but it is perfectly
  152. acceptable.  Any instruction that requires 1 or more string parameters may
  153. use a string label except where noted.
  154.  
  155.  *** For program clarity it is recommended that you define all numeric and
  156. string variables at the start of your source code.
  157.  
  158. DISPLAY
  159.  
  160.      Allows you to print a string or number to your screen (similar to
  161. BASIC's "PRINT" statement).
  162.  
  163.      Syntax: DISPLAY string{CBM-@}label
  164.              DISPLAY numeric{CBM-@}label
  165.              DISPLAY "literal string"
  166.              DISPLAY 'literal string'
  167.  
  168.      You may display literal strings, string labels, and numeric labels.
  169. You cannot display literal values (DISPLAY 123 is invalid)
  170.  
  171. TRANSMIT
  172.  
  173.      Functionally indentical to the DISPLAY instruction except that output
  174. is directed to the modem.
  175.  
  176.      Syntax: TRANSMIT string{CBM-@}label
  177.              TRANSMIT numeric{CBM-@}label
  178.              TRANSMIT "literal string"
  179.              TRANSMIT 'literal string'
  180.  
  181.      You may transmit literal strings, string labels, and numeric labels.
  182. You cannot transmit literal values (DISPLAY 123 is invalid)
  183.  
  184. TERMINAL
  185.  
  186.      Enters terminal mode and lights up the "S" script executing LED
  187. immediately to the right of the bytes free display.
  188.  
  189.      Syntax: TERMINAL
  190.  
  191. EDIT
  192.  
  193.      Enters the buffer editor.  You may then freely edit the buffer.  When
  194. you exit the editor control returns to the script.
  195.  
  196.      Syntax: EDIT
  197.  
  198.      This can be useful should you need to have checkpoints in a script
  199. where you check the buffer.  It can also be used on BOOTUP by first loading
  200. a file with the BLOAD instruction followed by the EDIT instruction.  This
  201. enables you to provide some documentation or automatically load a regularly
  202. used file.
  203.  
  204. DEVICE
  205.  
  206.      Allows you to change the default system device.
  207.  
  208.      Syntax: DEVICE x y
  209.  
  210. where x is the device